package Data::Timeline;

use strict;
use warnings;


our $VERSION = '0.03';


use base qw(Class::Accessor::Complex Class::Accessor::Constructor);


__PACKAGE__
    ->mk_constructor
    ->mk_array_accessors(qw(entries));


sub merge_timeline {
    my ($self, $timeline) = @_;

    $self->entries(
        sort { $a->timestamp <=> $b->timestamp }
        ($self->entries, $timeline->entries)
    );

    $self;    # for chaining
}


sub filter_timeline_by_type {
    my ($self, $type) = @_;
    Data::Timeline->new(entries => grep { $_->type eq $type } $self->entries);
}


sub filter_timeline_by_date {
    my ($self, $from, $to) = @_;
    Data::Timeline->new(entries =>
        grep { ($from <= $_->timestamp) && ($_->timestamp <= $to) }
        $self->entries
    );
}


1;


__END__

{% USE p = PodGenerated %}

=head1 NAME

{% p.package %} - Timelines

=head1 SYNOPSIS

    my $timeline = Data::Timeline->new;
    $timeline->entries_push(Data::Timeline::Entry->new(...));
    $timeline->merge_timeline($other_timeline);

=head1 DESCRIPTION

This class represents a timeline, which is a collection of timeline entry
objects (see L<Data::Timeline::Entry>).

=head1 METHODS

=over 4

{% p.write_methods %}

=item merge_timeline

    $timeline->merge_timeline($other_timeline);

Takes a timeline object and merges its entries into this timeline. The
resulting entry collection is sorted by timestamp.

=item filter_timeline_by_type

    my $other_timeline = $timeline->filter_timeline_by_type('iscrobbler');

Takes a string argument and returns a new timeline object containing only
those entries that match the given entry type.

Returns a new timeline object

=item filter_timeline_by_date

    my $other_timeline = $timeline->filter_timeline_by_date($from, $to);

Takes two L<DateTime> objects and returns a new timeline object containing
only those entries that occurred at or after the first argument and at or
before the second argument.

=back

{% p.write_inheritance %}

{% PROCESS standard_pod %}

=cut

